<html>
<head>
<title>Carrot From 10km</title>
<link href="carrot.css" rel="stylesheet" />
</head>

<body>

<div id="side">
  <img id="logo" src="/logos/fp300.png" alt="Firepear Logo"/>
  </ul>
</div>

<h1>Carrot From 10,000 Meters</h1>

<h2>1 - What's Carrot?</h2>

<p>
  It is a markup language.
</p>

<ul>
<li>
If you're familiar with HMTL, it's kinda like that. You have a source
document containing text and markup, which is rendered as a finished
document for viewing.
</li><li>
If you're familiar with Wiki formatting, it's kinda like that. The
markup isn't as full of annoying characters as HTML. Paragraphs of
plain text in the source gets you paragraphs of plain text in the
finished document.
</li><li>
If you're familiar with XML, it's kinda like that. The language itself
is extensible. Documents must be well-formed and valid.
</li><li>
If you're familiar with TeX, it's kinda like that. It tries to handle
fiddly, irritating things like numbering and pagination for you. It
supports concepts like document classes. A single source document can
produce output in many formats.
</li><li>
If you're familiar with Perl, it's kinda like that. It tries to be
strict where it makes sense, while making concessions to the humans
who are trying to get a job done. It lets the computer handle complexity
when it's possible.
</li>
</ul>
<p>
Carrot is not bound to the web, or any other medium. Carrot's native
output format is a datastructure (if these words make you teary-eyed,
welcome home; if you don't understand them, I promise you won't have
to fiddle with it). Carrot is not owned by anyone or encumbered by
anything.
</p>
<p>
Carrot is designed to be survivable and adaptable. Carrot will be
around for a long time. Carrot will change and grow.
</p>


<h2>2 - Carrot Looks Like This</h2>

<pre>
;;; for mr. steves's 4th period english (sucks)
[[document title;'My Summer Vacation' date;2019-08-22
           author;'Ramona Cartwright']]

This year's vacation was a lot of fun, and we did a bunch of
stuff.

[[section title;'Grandma's House'
  Our first stop was Grandma's. It's always cool to visit her
  because she used to work at [link uri;http://google.com
  Google], and she tells the best stories.

  I love Grandma!
]]
</pre>

<p>We may as well start at the beginning.</p>

<pre>
<span>;;; for mr. steves's 4th period english (sucks)</span>
[[document title;'My Summer Vacation' date;2019-08-22
           author;'Ramona Cartwright']]

This year's vacation was a lot of fun, and we did a bunch of
</pre>

<p>
The first line of our sample doc is a comment. Comments start with three semicolons and run to end-of-line. There are no multiline comments.
</p>

<pre>
;;; for mr. steves's 4th period english (sucks)
<span>[[document title;'My Summer Vacation' date;2019-08-22
           author;'Ramona Cartwright']]</span>

This year's vacation was a lot of fun, and we did a bunch of
</pre>

<p>
The highlighted portion here is the <em>document trigger</em>. All
Carrot documents must begin with a document trigger.
</p><p>
It contains metadata about the document. This can include simple
things like document titles (seen above) and more complex things like
instructions to the Carrot compiler (which we'll see later).
</p>

<pre>
;;; for mr. steves's 4th period english (sucks)
<span>[[</span>document title;'My Summer Vacation' date;2019-08-22
           author;'Ramona Cartwright'<span>]]</span>

This year's vacation was a lot of fun, and we did a bunch of
</pre>

<p>The document trigger is bounded by two square brackets. Left
brackets for open; right brackets for close. The opening brackets must
be the <b>first</b> characters on a new line, and the closing brackets
must be the <b>last</b> characters on a line.</p>


<pre>
[[document title;'My Summer Vacation' date;2019-08-22
           author;'Ramona Cartwright']]
     ...
[[section title;'Grandma's House'
  Our first stop was Grandma's. It's always cool to visit her
     ...
  I love Grandma!
]]
</pre>

<p>Notice that the chunk of text labelled <em>section</em> shares
some formatting with the document trigger.</p>

<p>
This is because they are <b>both</b> triggers. Where HTML/XML have one type
of markup (the tag), Carrot has three distinct forms: triggers, tags,
and verbatim chunks. Each has a different job to do in the document,
but all share common markup characters and formatting.
</p>

<h2>3 - Triggers</h2>

<p>The job of triggers is <em>to mark logical blocks of content within
the document.</em></p>

<p>
The document trigger contains information about the document. A
section trigger groups paragraphs of text into sections or
subsections. Triggers provide <em>structure</em> to the document.
</p>

<h3>3.1 - Names</h3>
<pre>
[[<span>document</span> title;'My Summer Vacation' date;2019-08-22
           author;'Ramona Cartwright']]
     ...
[[<span>section</span> title;'Grandma's House'
  Our first stop was Grandma's. It's always cool to visit her
     ...
  I love Grandma!
]]
</pre>
<p>A trigger's name always immediately follows its opening brackets
(no spaces allowed).</p>
<p>The name simply says what kind of trigger it is.</p>

<h3>3.2 - Attributes</h3>
<pre>
[[document <span>title;'My Summer Vacation'</span> <span>date;2019-08-22</span>
           <span>author;'Ramona Cartwright'</span>]]
     ...
[[section <span>title;'Grandma's House'</span>
  Our first stop was Grandma's. It's always cool to visit her
     ...
  I love Grandma!
]]
</pre>
<p>
Following the trigger's name are its attributes. A trigger can have
many attributes, or one, or none. Each trigger has its own set of
attributes. That is to say, not all triggers accept all attributes.
</p><p>
Attributes are key-value pairs, with a semicolon separating the key
and value. Attributes are separated from each other by whitespace.
</p>
<pre>
[[document <span>title</span>;'My Summer Vacation' <span>date</span>;2019-08-22
           <span>author</span>;'Ramona Cartwright']]
     ...
[[section <span>title</span>;'Grandma's House'
  Our first stop was Grandma's. It's always cool to visit her
     ...
  I love Grandma!
]]
</pre>
<p>Attribute keys never contain spaces.</p>
<pre>
[[document title;<span>'My Summer Vacation'</span> date;2019-08-22
           author;<span>'Ramona Cartwright'</span>]]
     ...
[[section title;<span>'Grandma's House'</span>
  Our first stop was Grandma's. It's always cool to visit her
     ...
  I love Grandma!
]]
</pre>
<p>
Attribute values may contain whitespace, but if so, they must be
bounded by single-quotes.
</p>
<pre>
[[section title;<span>'Grandma's House'</span>
  Our first stop was Grandma's. It's always cool to visit her
     ...
  I love Grandma!
]]
</pre>
<p>
Unlike most languages, Carrot allows the quote character to occur
inside quotes, so long as it is within a word. (It's possible to have
a quote at the end of a word, or even standing alone, but we'll cover
that later.)
</p>

<h3>3.3 - Content</h3>
<pre>
[[document title;'My Summer Vacation' date;2019-08-22
           author;'Ramona Cartwright']]

This year's vacation was a lot of fun, and we did a bunch of
stuff.

[[section title;'Grandma's House'
  <span>Our first stop was Grandma's. It's always cool to visit her</span>
  <span>because she used to work at [link uri;http://google.com    </span>
  <span>Google], and she tells the best stories.                   </span>

  <span>I love Grandma!</span>
]]
</pre>
<p>The highlighted text is the content of the section trigger.</p>
<p>
Not all triggers have content &mdash; the document trigger doesn't
&mdash; but most of them do. Content may be simple paragraphs of text,
as it is here, or it may be more highly structured, as in a trigger
which generates a list of some sort.
</p>

<h3>3.4 - Formatting Details</h3>
<pre>
[[document title;'My Summer Vacation' date;2019-08-22
           author;'Ramona Cartwright'<span>]]</span>
    ...
[[section title;'Grandma's House'
  Our first stop was Grandma's. It's always cool to visit her
    ...
  I love Grandma!
<span>]]</span>
</pre>
<p>
Closing brackets do have to be the last thing on a line, but
they <b>don't</b> have to be on the same line as the content of the
trigger. They can be separated from the content by any amount of
whitespace.
</p>
<pre>
[[section title;'Grandma's House'
<span>  </span>Our first stop was Grandma's. It's always cool to visit her
<span>  </span>because she used to work at [link uri;http://google.com    
<span>  </span>Google], and she tells the best stories.                   
<span>  </span>
<span>  </span>I love Grandma!
]]
</pre>
<p>Like most programming and/or markup languages, indention is not
neccessary, but it does look nice and provide important visual
cues.</p>
<pre>
[[section title;'Grandma's House'
  Our first stop was Grandma's. It's always cool to visit her
  ...
</pre>
<p>
There is no markup which separates attributes from content, or
attributes from trigger names, or trigger names from content.
</p><p>
All have distinct forms and the compiler knows this, so you
don't have to waste time, typing, or thought on it.
</p>


<h2>4 - Tags</h2>

<p>
The job of tags is <em>to handle markup which is inline of text content.</em>.
</p>
<pre>
Our first stop was Grandma's. It's always cool to visit her
because she used to work at <span>[link uri;http://google.com</span>
<span>Google]</span>, and she tells the best stories.
</pre>
<p>The highlighted text above is a tag.</p>
<p>Tags have two immediately noticable differences from triggers:</p>
<ol>
<li>They are bounded by pairs of single left/right square brackets</li>
<li>They can occur anywhere on a line</li>
</ol>
<p>Nearly everything else about them is the same.
<pre>
because she used to work at [<span>link</span> uri;http://google.com
Google], and she tells the best stories.
</pre>
<p>
They have names, which must be adjacent to their opening bracket.
</p>
<pre>
because she used to work at [link <span>uri;http://google.com</span>
Google], and she tells the best stories.
</pre>
<p>
They can have attributes (one, or many, or none), which look and
behave exactly the same as trigger attributes.
</p>
<pre>
because she used to work at [link uri;http://google.com
<span>Google</span>], and she tells the best stories.
</pre>
<p>
They can (and usually will) have textual content, which is somehow
modified or used by the tag.
</p>
<pre>
because she used to work at <span>[link uri;http://google.com
<span class='bad'>[[list type;unordered
  -- Google and      </span></span>  ;;; no no no
<span class='bad'>  -- Baidu and       
  -- Moto]]</span><span> ]</span>, and she tells the best stories.
</pre>
<p>
Finally, triggers can contain tags, but tags can <b>never</b> contain
triggers (or verbatim chunks).
</p>

<h2>5 - Verbatim Chunks</h2>

<p>The job of verbatim chunks is <em>to contain text which should not be transformed</em>.</p>

<pre>
[[section title;'Carrot Looks Like This'

[[[code
<span> ;;; for mr. steves's 4th period english (sucks)
 [[document title;'My Summer Vacation' date;2019-08-22
            author;'Ramona Cartwright']]
     
 This year's vacation was a lot of fun, and we did a bunch of</span>
]]]

We may as well start at the beginning.
</pre>
<p>
No processing will be done on the highlighted text above. It will all
simply be stored for later presentation. All whitespace will be
preserved.
</p>
<pre>
<span>[[[</span>code
 ;;; for mr. steves's 4th period english (sucks)
 [[document title;'My Summer Vacation' date;2019-08-22
            author;'Ramona Cartwright']]
     
 This year's vacation was a lot of fun, and we did a bunch of
<span>]]]</span>
</pre>
<p>
Verbatim chunks open with treble left square brackets, and (like
triggers) they must begin on a new line.
</p>
<p>
Verbatim chunks close with treble right square brackets, and these
(unlike triggers) must be the <b>only</b> thing on that line. Not even
whitespace is allowable. This is to enable text which would normally
be interpreted as a verbatim chunk to be unambiguously included in
verbatim chunks.
</p>
<p>
Verbatim chunks can be contained inside triggers, but, self-evidently,
neither triggers or tags can exist in a meaningful way inside a
verbatim chunk.
</p>

<h2>6 - And A Peek At All The Rest</h2>

<h3>6.1 - Entities</h3>
<p>
HTML uses <em>entities</em> to include "unusual" characters in
documents. Carrot does too, but they have two forms.
</p>
<pre>
Hello.
[H][e][l][l][o][.]
</pre>
<p>
The first form is actually a generalized escape, like the Unix
convention of preceeding a character with a backslash. Any single
character between a pair of square brackets is equivalent to that
character. Therefore, post-processing, the above lines of text are
equivalent.
</p>
<pre>
title;'The Dog Is The Boys[']'
</pre>
<p>
You may have already figured out that this is how you get a
singlequote at the beginning or end of a quoted attribute value.
</p>
<pre>
S[e'][c,][o&quot;][n~]d[->]f[o/]rm entities
S&eacute;&ccedil;&ouml;&ntilde;d&rarr;f&oslash;rm entities
</pre>
<p>
Any pair of characters bounded by square brackets will be looked up and replaced with a single character which they have been mapped to. This is directly analagous to HTML entities.
</p>
<p>
You may be wondering if entities are a general-purpose macro system, in the style of the C preprocessor. I believe the answer is (and should be) "No."
</p>
<p>
You may be exceptionally troublesome, and wondering if entities are
resolved inside verbatim chunks. I believe the answer is (and should
be) "Yes."
</p>

<h3>6.2 - Compact Forms</h3>
<pre>
[[section title;Foo
[[s t;Foo

[[list type;ordered
[[l t;o
</pre>
<p>
If you were asking why a language so concerned with saving typing had
such long element and attribute names, you can take it easy. All
elements and attribute names <em>can be</em> aliased to abbreviated
forms. Please note that the above examples are abstract, and for
illustrative purposes only.
</p>

<h3>6.3 - Internationalization</h3>
<p>
"Well, then," you say, "what about your carefully chosen markup characters? They're all unshifted on a US keyboard, but there are other keyboards, you ignorant cultural imperialist!"
</p>
<pre>
;;; altered markup
[[docinfo markup;&lt;&gt;=&quot;*]]

&lt;&lt;section title="Faux HTML"

Now my markup looks like weird HTML.&gt;&gt;
</pre>
<p>
Carrot's language definition isn't hardcoded. It is possible to
redefine almost everything, including the very characters used to
delineate markup. The only caveat is that the document trigger
must <b>always</b> use the standard markup characters.
</p>
<p>
Additionally, the aliasing mechanism described in the previous section
lets all the names in the system have equivalents in the author's
native language (again, excepting those in the document trigger).
</p><p> 
In short: Carrot's is fully localizable. It will be easy to type
no matter where you are.</p>

<h3>6.4 - Customization and Extension</h3>
<p>
The Carrot system will be customizable in the usual manner, with
per-system and per-user option configurations.
</p>
<p>
Users and system admins can also define local aliases and entities,
write whole new markup element handlers, or rewrite existing ones to
better suit their needs. Carrot's design does not presume to foresee
everything.
</p>
<p>
It is, in fact, hoped that Carrot will attract an active community of
users and contributors, and that a CPAN-like repository of contributed
modules will be available for everyone to use.
</p>
<p>
With or without a CPAN-alike, there will be a way to safely write
documents using local modifications without worrying about other
people having those modifications in their Carrot installs. A scheme
called "document export" is being developed, which will check
documents for nonstandard markups and include processing instructions
for them inside the exported document itself, as checksummed,
compressed data. It's pretty swank.
</p>

<h2>7 - Conclusion</h2>
<p>
You should now know what Carrot is, some of the problems it was
designed to solve, and the basics of its structure and rules. You've
also had a peek at some specific features which are less basic, but
there's much more to see.
</p>
<p>
Portions of this document are forward-looking, but nothing described
herein is vaporware. Almost all features and designs have had their
implementation problems "cracked", and will be real software
relatively shortly. (The one lingering unknown is how to create
pluggable output modules, but there is much work to be done
between the present day and that problem <em>needing</em> to be
solved.)
<p>
Carrot is coming, and sooner rather than later :)
</p>

</body>
</html>
